home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / CoreFoundation / CFString.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  27.0 KB  |  725 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        CFString.h
  3.  
  4.      Contains:    CoreFoundation strings
  5.  
  6.      Version:    Technology:    Mac OS X
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1999 by Apple Computer, Inc., all rights reserved
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __COREFOUNDATION_CFSTRING__
  18. #define __COREFOUNDATION_CFSTRING__
  19.  
  20. #ifndef __COREFOUNDATION_CFBASE__
  21.     #include <CoreFoundation\CFBase.h>
  22. #endif
  23.  
  24. #ifndef __COREFOUNDATION_CFARRAY__
  25.     #include <CoreFoundation\CFArray.h>
  26. #endif
  27.  
  28. #ifndef __COREFOUNDATION_CFDATA__
  29.     #include <CoreFoundation\CFData.h>
  30. #endif
  31.  
  32. #ifndef __COREFOUNDATION_CFDICTIONARY__
  33.     #include <CoreFoundation\CFDictionary.h>
  34. #endif
  35.  
  36.  
  37. #include <stdarg.h>
  38.  
  39.  
  40. #if PRAGMA_ONCE
  41. #pragma once
  42. #endif
  43.  
  44. #ifdef __cplusplus
  45. extern "C" {
  46. #endif
  47.  
  48. #if PRAGMA_IMPORT
  49. #pragma import on
  50. #endif
  51.  
  52. #if PRAGMA_STRUCT_ALIGN
  53.     #pragma options align=mac68k
  54. #elif PRAGMA_STRUCT_PACKPUSH
  55.     #pragma pack(push, 2)
  56. #elif PRAGMA_STRUCT_PACK
  57.     #pragma pack(2)
  58. #endif
  59.  
  60. /*
  61. Please note: CFStrings are conceptually an array of Unicode characters.
  62. However, in general, how a CFString stores this array is an implementation
  63. detail. For instance, CFString might choose to use an array of 8-bit characters;
  64. to store its contents; or it might use multiple blocks of memory; or whatever.
  65. Furthermore, the implementation might change depending on the default
  66. system encoding, the user's language, the OS, or even a given release.
  67.  
  68. What this means is that you should use the following advanced functions with care:
  69.  
  70.   CFStringGetPascalStringPtr()
  71.   CFStringGetCStringPtr()
  72.   CFStringGetCharactersPtr()
  73.  
  74. These functions either return the desired pointer quickly, in constant time, or they
  75. return NULL, which indicates you should use some of the other function, as shown 
  76. in this example: 
  77.  
  78.     Str255 buffer;
  79.     StringPtr ptr = CFStringGetPascalStringPtr(str, encoding);
  80.     if (ptr == NULL) {
  81.     if (CFStringGetPascalString(str, buffer, 256, encoding)) ptr = buffer;
  82.     }
  83.  
  84. Note that CFStringGetPascalString call might still return NULL --- but that will happen 
  85. in two circumstances only: The conversion from the UniChar contents of CFString
  86. to the specified encoding fails, or the buffer is too small. 
  87.  
  88. If you need a copy of the buffer in the above example, you might consider simply
  89. calling CFStringGetPascalString() in all cases --- CFStringGetPascalStringPtr()
  90. is simply an optimization.
  91.  
  92. In addition, the following functions, which create immutable CFStrings from developer
  93. supplied buffers without copying the buffers, might have to actually copy
  94. under certain circumstances (If they do copy, the buffer will be dealt by the
  95. "contentsDeallocator" argument.):
  96.  
  97.   CFStringCreateWithPascalStringNoCopy()
  98.   CFStringCreateWithCStringNoCopy()
  99.   CFStringCreateWithCharactersNoCopy()
  100.  
  101. You should of course never depend on the backing store of these CFStrings being
  102. what you provided, and in other no circumstance should you change the contents
  103. of that buffer (given that would break the invariant about the CFString being immutable).
  104.  
  105. Having said all this, there are actually ways to create a CFString where the backing store
  106. is external, and can be manipulated by the developer or CFString itself:
  107.  
  108.   CFStringCreateMutableWithExternalCharactersNoCopy()
  109.   CFStringSetExternalCharactersNoCopy()
  110.  
  111. A "contentsAllocator" is used to realloc or free the backing store by CFString.
  112. kCFAllocatorNull can be provided to assure CFString will never realloc or free the buffer.
  113. Developer can call CFStringSetExternalCharactersNoCopy() to update
  114. CFString's idea of what's going on, if the buffer is changed externally. In these
  115. strings, CFStringGetCharactersPtr() is guaranteed to return the external buffer.
  116.  
  117. These functions are here to allow wrapping a buffer of UniChar characters in a CFString,
  118. allowing the buffer to passed into CFString functions and also manipulated via CFString
  119. mutation functions. In general, developers should not use this technique for all strings,
  120. as it prevents CFString from using certain optimizations.
  121. */
  122. /*
  123.     CFStringRef and CFMutableStringRef are defined in CFBase.h
  124. */
  125.  
  126. /* Identifier for character encoding; the values are the same as Text Encoding Converter TextEncoding.
  127. */
  128. typedef UInt32                             CFStringEncoding;
  129. /* Platform-independent built-in encodings; always available on all platforms.
  130. */
  131. enum {
  132.     kCFStringEncodingInvalidId    = -1L,
  133.     kCFStringEncodingMacRoman    = 0L,
  134.     kCFStringEncodingWindowsLatin1 = 0x0500,                    /* ANSI codepage 1252 */
  135.     kCFStringEncodingISOLatin1    = 0x0201,                        /* ISO 8850 1 */
  136.     kCFStringEncodingNextStepLatin = 0x0B01,                    /* NextStep encoding*/
  137.     kCFStringEncodingASCII        = 0x0600,                        /* 0..127 */
  138.     kCFStringEncodingUnicode    = 0x0100,                        /* kTextEncodingUnicodeDefault  + kTextEncodingDefaultFormat (aka kUnicode16BitFormat) */
  139.     kCFStringEncodingUTF8        = 0x08000100,                    /* kTextEncodingUnicodeDefault + kUnicodeUTF8Format */
  140.     kCFStringEncodingNonLossyASCII = 0x0BFF                        /* 7bit Unicode variants used by YellowBox & Java */
  141. };
  142.  
  143.  
  144. /* CFString type ID
  145. */
  146. EXTERN_API_C( CFTypeID )
  147. CFStringGetTypeID                (void);
  148.  
  149. /* Macro to allow creation of compile-time constant strings; the argument should be a constant string. This will work for now but we need something better.
  150. */
  151. #define CFSTR(cStr)  __CFStringMakeConstantString(cStr "")
  152.  
  153. /*** Immutable string creation functions ***/
  154. /* Functions to create basic immutable strings. The provided allocator is used for all memory activity in these functions.
  155. */
  156. /* These functions copy the provided buffer into CFString's internal storage.
  157. */
  158. EXTERN_API_C( CFStringRef )
  159. CFStringCreateWithPascalString    (CFAllocatorRef         alloc,
  160.                                  ConstStringPtr         pStr,
  161.                                  CFStringEncoding         encoding);
  162.  
  163. EXTERN_API_C( CFStringRef )
  164. CFStringCreateWithCString        (CFAllocatorRef         alloc,
  165.                                  const char *            cStr,
  166.                                  CFStringEncoding         encoding);
  167.  
  168. EXTERN_API_C( CFStringRef )
  169. CFStringCreateWithCharacters    (CFAllocatorRef         alloc,
  170.                                  const UniChar *        chars,
  171.                                  CFIndex                 numChars);
  172.  
  173. /* These functions try not to copy the provided buffer. The buffer will be 
  174. deallocated with the provided contentsDeallocator when it's no longer needed;
  175. to not free the buffer, specify kCFAllocatorNull here. As usual, NULL means
  176. default allocator.
  177. NOTE: Do not count on these buffers as being used by the string; 
  178. in some cases the CFString might free the buffer and use something else
  179. (for instance if it decides to always use Unicode encoding internally). 
  180. In addition, some encodings are not used internally; in
  181. those cases CFString might also dump the provided buffer and use its own.
  182. */
  183.  
  184. EXTERN_API_C( CFStringRef )
  185. CFStringCreateWithPascalStringNoCopy (CFAllocatorRef     alloc,
  186.                                  ConstStringPtr         pStr,
  187.                                  CFStringEncoding         encoding,
  188.                                  CFAllocatorRef         contentsDeallocator);
  189.  
  190. EXTERN_API_C( CFStringRef )
  191. CFStringCreateWithCStringNoCopy    (CFAllocatorRef         alloc,
  192.                                  const char *            cStr,
  193.                                  CFStringEncoding         encoding,
  194.                                  CFAllocatorRef         contentsDeallocator);
  195.  
  196. EXTERN_API_C( CFStringRef )
  197. CFStringCreateWithCharactersNoCopy (CFAllocatorRef         alloc,
  198.                                  const UniChar *        chars,
  199.                                  CFIndex                 numChars,
  200.                                  CFAllocatorRef         contentsDeallocator);
  201.  
  202. /* Create copies of part or all of the string.
  203. */
  204. EXTERN_API_C( CFStringRef )
  205. CFStringCreateWithSubstring        (CFAllocatorRef         alloc,
  206.                                  CFStringRef             str,
  207.                                  CFRange                 range);
  208.  
  209. EXTERN_API_C( CFStringRef )
  210. CFStringCreateCopy                (CFAllocatorRef         alloc,
  211.                                  CFStringRef             theString);
  212.  
  213. /* These functions create a CFString from the provided printf-format and arguments.
  214. */
  215. EXTERN_API_C( CFStringRef )
  216. CFStringCreateWithFormat        (CFAllocatorRef         alloc,
  217.                                  CFDictionaryRef         formatOptions,
  218.                                  CFStringRef             format,
  219.                                  ...);
  220.  
  221. EXTERN_API_C( CFStringRef )
  222. CFStringCreateWithFormatAndArguments (CFAllocatorRef     alloc,
  223.                                  CFDictionaryRef         formatOptions,
  224.                                  CFStringRef             format,
  225.                                  va_list                 arguments);
  226.  
  227. /* Functions to create mutable strings. "maxLength", if not 0, is a hard bound on the length of the string. If 0, there is no limit on the length.
  228. */
  229. EXTERN_API_C( CFMutableStringRef )
  230. CFStringCreateMutable            (CFAllocatorRef         alloc,
  231.                                  CFIndex                 maxLength);
  232.  
  233. EXTERN_API_C( CFMutableStringRef )
  234. CFStringCreateMutableCopy        (CFAllocatorRef         alloc,
  235.                                  CFIndex                 maxLength,
  236.                                  CFStringRef             theString);
  237.  
  238. /* This function creates a mutable string that has a developer supplied and directly editable backing store.
  239. The string will be manipulated within the provided buffer (if any) until it outgrows capacity; then the
  240. externalCharactersAllocator will be consulted for more memory. When the CFString is deallocated, the
  241. buffer will be freed with the externalCharactersAllocator. Provide kCFAllocatorNull here to prevent the buffer
  242. from ever being reallocated or deallocated by CFString. See comments at top of this file for more info.
  243. */
  244. EXTERN_API_C( CFMutableStringRef )
  245. CFStringCreateMutableWithExternalCharactersNoCopy (CFAllocatorRef  alloc,
  246.                                  UniChar *                chars,
  247.                                  CFIndex                 numChars,
  248.                                  CFIndex                 capacity,
  249.                                  CFAllocatorRef         externalCharactersAllocator);
  250.  
  251.  
  252. /*** Basic accessors for the contents ***/
  253. /* Number of 16-bit Unicode characters in the string.
  254. */
  255. EXTERN_API_C( CFIndex )
  256. CFStringGetLength                (CFStringRef             theString);
  257.  
  258. /* Extracting the contents of the string. For obtaining multiple characters, calling
  259. CFStringGetCharacters() is more efficient than multiple calls to CFStringGetCharacterAtIndex().
  260. If the length of the string is not known (so you can't use a fixed size buffer for CFStringGetCharacters()),
  261. another method is to use is CFStringGetCharacterFromInlineBuffer() (see further below).
  262. */
  263. EXTERN_API_C( UniChar )
  264. CFStringGetCharacterAtIndex        (CFStringRef             theString,
  265.                                  CFIndex                 idx);
  266.  
  267. EXTERN_API_C( void )
  268. CFStringGetCharacters            (CFStringRef             theString,
  269.                                  CFRange                 range,
  270.                                  UniChar *                buffer);
  271.  
  272.  
  273. /*** Conversion to other encodings ***/
  274.  
  275. /* These two convert into the provided buffer; they return FALSE if conversion isn't possible
  276. (due to conversion error, or not enough space in the provided buffer). 
  277. These functions do zero-terminate or put the length byte; the provided bufferSize should include
  278. space for this (so pass 256 for Str255). More sophisticated usages can go through CFStringGetBytes().
  279. */
  280. EXTERN_API_C( Boolean )
  281. CFStringGetPascalString            (CFStringRef             theString,
  282.                                  StringPtr                 buffer,
  283.                                  CFIndex                 bufferSize,
  284.                                  CFStringEncoding         encoding);
  285.  
  286. EXTERN_API_C( Boolean )
  287. CFStringGetCString                (CFStringRef             theString,
  288.                                  char *                    buffer,
  289.                                  CFIndex                 bufferSize,
  290.                                  CFStringEncoding         encoding);
  291.  
  292. /* These functions attempt to return in O(1) time the desired format for the string.
  293. Note that although this means a pointer to the internal structure is being returned,
  294. this can't always be counted on. Please see note at the top of the file for more
  295. details.
  296. */
  297. EXTERN_API_C( ConstStringPtr )
  298. CFStringGetPascalStringPtr        (CFStringRef             theString,
  299.                                  CFStringEncoding         encoding);
  300.  
  301. /* Be prepared for NULL */
  302. EXTERN_API_C( const char *)
  303. CFStringGetCStringPtr            (CFStringRef             theString,
  304.                                  CFStringEncoding         encoding);
  305.  
  306. /* Be prepared for NULL */
  307. EXTERN_API_C( const UniChar *)
  308. CFStringGetCharactersPtr        (CFStringRef             theString);
  309.  
  310. /* Be prepared for NULL */
  311. /* The primitive conversion routine; allows you to convert a string piece at a time
  312.    into a fixed size buffer. Returns number of characters converted. 
  313.    Characters that cannot be converted to the specified encoding are represented
  314.    with the byte specified by lossByte; if lossByte is 0, then lossy conversion
  315.    is not allowed and conversion stops, returning partial results.
  316.    Pass buffer==NULL if you don't care about the converted string (but just the convertability,
  317.    or number of bytes required, indicated by usedBufLen). 
  318.    maxBufLength indicates the maximum number of bytes to generate; it is consulted even
  319.    if buffer is NULL, so pass in INT_MAX if you want to find out the maximum number of bytes.
  320.    Does not zero-terminate. If you want to create Pascal or C string, allow one extra byte at start or end. 
  321.    Setting isExternalRepresentation causes any extra bytes that would allow 
  322.    the data to be made persistent to be included; for instance, the Unicode BOM.
  323. */
  324. EXTERN_API_C( CFIndex )
  325. CFStringGetBytes                (CFStringRef             theString,
  326.                                  CFRange                 range,
  327.                                  CFStringEncoding         encoding,
  328.                                  UInt8                     lossByte,
  329.                                  Boolean                 isExternalRepresentation,
  330.                                  UInt8 *                buffer,
  331.                                  CFIndex                 maxBufLen,
  332.                                  CFIndex *                usedBufLen);
  333.  
  334. /* This one goes the other way by creating a CFString from a bag of bytes. 
  335. This is much like CFStringCreateWithPascalString or CFStringCreateWithCString, 
  336. except the length is supplied explicitly. In addition, you can specify whether 
  337. the data is an external format --- that is, whether to pay attention to the 
  338. BOM character (if any) and do byte swapping if necessary
  339. */
  340. EXTERN_API_C( CFStringRef )
  341. CFStringCreateWithBytes            (CFAllocatorRef         alloc,
  342.                                  const UInt8 *            bytes,
  343.                                  CFIndex                 numBytes,
  344.                                  CFStringEncoding         encoding,
  345.                                  Boolean                 isExternalRepresentation);
  346.  
  347. /* Convenience functions String <-> Data. These generate "external" formats, that is, formats that
  348.    can be written out to disk. For instance, if the encoding is Unicode, CFStringCreateFromExternalRepresentation()
  349.    pays attention to the BOM character (if any) and does byte swapping if necessary.
  350.    Similarly CFStringCreateExternalRepresentation() will always include a BOM character if the encoding is
  351.    Unicode. See above for description of lossByte.
  352. */
  353. EXTERN_API_C( CFStringRef )
  354. CFStringCreateFromExternalRepresentation (CFAllocatorRef  alloc,
  355.                                  CFDataRef                 data,
  356.                                  CFStringEncoding         encoding);
  357.  
  358. /* May return NULL on conversion error */
  359. EXTERN_API_C( CFDataRef )
  360. CFStringCreateExternalRepresentation (CFAllocatorRef     alloc,
  361.                                  CFStringRef             theString,
  362.                                  CFStringEncoding         encoding,
  363.                                  UInt8                     lossByte);
  364.  
  365. /* May return NULL on conversion error */
  366. /* Hints about the contents of a string
  367. */
  368. EXTERN_API_C( CFStringEncoding )
  369. CFStringGetSmallestEncoding        (CFStringRef             theString);
  370.  
  371. /* Result in O(n) time max */
  372. EXTERN_API_C( CFStringEncoding )
  373. CFStringGetFastestEncoding        (CFStringRef             theString);
  374.  
  375. /* Result in O(1) time max */
  376. /* General encoding info
  377. */
  378. EXTERN_API_C( CFStringEncoding )
  379. CFStringGetSystemEncoding        (void);
  380.  
  381. /* The default encoding for the system; untagged 8-bit characters are usually in this encoding */
  382. EXTERN_API_C( CFIndex )
  383. CFStringGetMaximumSizeForEncoding (CFIndex                 length,
  384.                                  CFStringEncoding         encoding);
  385.  
  386. /* Max bytes a string of specified length (in UniChars) will take up if encoded */
  387.  
  388. /*** Comparison functions. ***/
  389. enum {
  390.                                                                 /* Flags used in all find and compare operations */
  391.     kCFCompareCaseInsensitive    = 1,
  392.     kCFCompareBackwards            = 4,                            /* Starting from the end of the string */
  393.     kCFCompareAnchored            = 8,                            /* Only at the specified starting point */
  394.     kCFCompareNonliteral        = 16,                            /* If specified, loose equivalence is performed (o-umlaut == o, umlaut) */
  395.     kCFCompareLocalized            = 32,                            /* User's default locale is used for the comparisons */
  396.     kCFCompareNumerically        = 64                            /* Numeric comparison is used; that is, Foo2.txt < Foo7.txt < Foo25.txt */
  397. };
  398.  
  399. /* The main comparison routine; compares specified range of the string to another.
  400.    locale == NULL indicates canonical locale
  401. */
  402. EXTERN_API_C( CFComparisonResult )
  403. CFStringCompareWithOptions        (CFStringRef             string1,
  404.                                  CFStringRef             string2,
  405.                                  CFRange                 rangeToCompare,
  406.                                  CFOptionFlags             compareOptions);
  407.  
  408. /* Comparison convenience suitable for passing as sorting functions.
  409. */
  410. EXTERN_API_C( CFComparisonResult )
  411. CFStringCompare                    (CFStringRef             string1,
  412.                                  CFStringRef             string2,
  413.                                  CFOptionFlags             compareOptions);
  414.  
  415. /* Find routines; CFStringFindWithOptions() returns the found range in the CFRange * argument;  You can pass NULL for simple discovery check.
  416.    CFStringCreateArrayWithFindResults() returns an array of CFRange pointers, or NULL if there are no matches.
  417. */
  418. EXTERN_API_C( Boolean )
  419. CFStringFindWithOptions            (CFStringRef             theString,
  420.                                  CFStringRef             stringToFind,
  421.                                  CFRange                 rangeToSearch,
  422.                                  CFOptionFlags             searchOptions,
  423.                                  CFRange *                result);
  424.  
  425. EXTERN_API_C( CFArrayRef )
  426. CFStringCreateArrayWithFindResults (CFAllocatorRef         alloc,
  427.                                  CFStringRef             theString,
  428.                                  CFStringRef             stringToFind,
  429.                                  CFRange                 rangeToSearch,
  430.                                  CFOptionFlags             compareOptions);
  431.  
  432. /* Find conveniences
  433. */
  434. EXTERN_API_C( CFRange )
  435. CFStringFind                    (CFStringRef             theString,
  436.                                  CFStringRef             stringToFind,
  437.                                  CFOptionFlags             compareOptions);
  438.  
  439. EXTERN_API_C( Boolean )
  440. CFStringHasPrefix                (CFStringRef             theString,
  441.                                  CFStringRef             prefix);
  442.  
  443. EXTERN_API_C( Boolean )
  444. CFStringHasSuffix                (CFStringRef             theString,
  445.                                  CFStringRef             suffix);
  446.  
  447. /* Find range of bounds of the line(s) that span the indicated range (startIndex, numChars),
  448.    taking into account various possible line separator sequences (CR, CRLF, LF, and Unicode LS, PS).
  449.    All return values are "optional" (provide NULL if you don't want them)
  450.      lineStartIndex: index of first character in line
  451.      lineEndIndex: index of first character of the next line (including terminating line separator characters)
  452.      contentsEndIndex: index of the first line separator character
  453.    Thus, lineEndIndex - lineStartIndex is the number of chars in the line, including the line separators
  454.          contentsEndIndex - lineStartIndex is the number of chars in the line w/out the line separators
  455. */
  456. EXTERN_API_C( void )
  457. CFStringGetLineBounds            (CFStringRef             theString,
  458.                                  CFRange                 range,
  459.                                  CFIndex *                lineBeginIndex,
  460.                                  CFIndex *                lineEndIndex,
  461.                                  CFIndex *                contentsEndIndex);
  462.  
  463. /*** Exploding and joining strings with a separator string ***/
  464.  
  465. EXTERN_API_C( CFStringRef )
  466. CFStringCreateByCombiningStrings (CFAllocatorRef         alloc,
  467.                                  CFArrayRef             theArray,
  468.                                  CFStringRef             separatorString);
  469.  
  470. /* Empty array returns empty string; one element array returns the element */
  471. EXTERN_API_C( CFArrayRef )
  472. CFStringCreateArrayBySeparatingStrings (CFAllocatorRef     alloc,
  473.                                  CFStringRef             theString,
  474.                                  CFStringRef             separatorString);
  475.  
  476. /* No separators in the string returns array with that string; string == sep returns two empty strings */
  477. /*** Parsing non-localized numbers from strings ***/
  478.  
  479. EXTERN_API_C( SInt32 )
  480. CFStringGetIntValue                (CFStringRef             str);
  481.  
  482. /* Skips whitespace; returns 0 on error, MAX or -MAX on overflow */
  483. EXTERN_API_C( double )
  484. CFStringGetDoubleValue            (CFStringRef             str);
  485.  
  486. /* Skips whitespace; returns 0.0 on error */
  487. /*** MutableString functions ***/
  488. /* CFStringAppend("abcdef", "xxxxx") -> "abcdefxxxxx"
  489.    CFStringDelete("abcdef", 2, 3) -> "abf"
  490.    CFStringReplace("abcdef", 2, 3, "xxxxx") -> "abxxxxxf"
  491.    CFStringReplaceAll("abcdef", "xxxxx") -> "xxxxx"
  492. */
  493. EXTERN_API_C( void )
  494. CFStringAppend                    (CFMutableStringRef     theString,
  495.                                  CFStringRef             appendedString);
  496.  
  497. EXTERN_API_C( void )
  498. CFStringAppendCharacters        (CFMutableStringRef     theString,
  499.                                  const UniChar *        chars,
  500.                                  CFIndex                 numChars);
  501.  
  502. EXTERN_API_C( void )
  503. CFStringAppendPascalString        (CFMutableStringRef     theString,
  504.                                  ConstStringPtr         pStr,
  505.                                  CFStringEncoding         encoding);
  506.  
  507. EXTERN_API_C( void )
  508. CFStringAppendCString            (CFMutableStringRef     theString,
  509.                                  const char *            cStr,
  510.                                  CFStringEncoding         encoding);
  511.  
  512. EXTERN_API_C( void )
  513. CFStringAppendFormat            (CFMutableStringRef     theString,
  514.                                  CFDictionaryRef         formatOptions,
  515.                                  CFStringRef             format,
  516.                                  ...);
  517.  
  518. EXTERN_API_C( void )
  519. CFStringAppendFormatAndArguments (CFMutableStringRef     theString,
  520.                                  CFDictionaryRef         formatOptions,
  521.                                  CFStringRef             format,
  522.                                  va_list                 arguments);
  523.  
  524. EXTERN_API_C( void )
  525. CFStringInsert                    (CFMutableStringRef     str,
  526.                                  CFIndex                 idx,
  527.                                  CFStringRef             insertedStr);
  528.  
  529. EXTERN_API_C( void )
  530. CFStringDelete                    (CFMutableStringRef     theString,
  531.                                  CFRange                 range);
  532.  
  533. EXTERN_API_C( void )
  534. CFStringReplace                    (CFMutableStringRef     theString,
  535.                                  CFRange                 range,
  536.                                  CFStringRef             replacement);
  537.  
  538. EXTERN_API_C( void )
  539. CFStringReplaceAll                (CFMutableStringRef     theString,
  540.                                  CFStringRef             replacement);
  541.  
  542. /* Replaces whole string */
  543. /* This function will make the contents of a mutable CFString point directly at the specified UniChar array.
  544. it works only with CFStrings created with CFStringCreateMutableWithExternalCharactersNoCopy().
  545. This function does not free the previous buffer.
  546. The string will be manipulated within the provided buffer (if any) until it outgrows capacity; then the
  547. externalCharactersAllocator will be consulted for more memory.
  548. See comments at the top of this file for more info.
  549. */
  550. EXTERN_API_C( void )
  551. CFStringSetExternalCharactersNoCopy (CFMutableStringRef  theString,
  552.                                  UniChar *                chars,
  553.                                  CFIndex                 length,
  554.                                  CFIndex                 capacity);
  555.  
  556. /* Works only on specially created mutable strings! */
  557.  
  558. /* CFStringPad() will pad or cut down a string to the specified size.
  559.    The pad string is used as the fill string; indexIntoPad specifies which character to start with.
  560.      CFStringPad("abc", " ", 9, 0) ->  "abc      "
  561.      CFStringPad("abc", ". ", 9, 1) -> "abc . . ."
  562.      CFStringPad("abcdef", ?, 3, ?) -> "abc"
  563.  
  564.      CFStringTrim() will trim the specified string from both ends of the string.
  565.      CFStringTrimWhitespace() will do the same with white space characters (tab, newline, etc)
  566.      CFStringTrim("  abc ", " ") -> "abc"
  567.      CFStringTrim("* * * *abc * ", "* ") -> "*abc "
  568. */
  569. EXTERN_API_C( void )
  570. CFStringPad                        (CFMutableStringRef     theString,
  571.                                  CFStringRef             padString,
  572.                                  CFIndex                 length,
  573.                                  CFIndex                 indexIntoPad);
  574.  
  575. EXTERN_API_C( void )
  576. CFStringTrim                    (CFMutableStringRef     theString,
  577.                                  CFStringRef             trimString);
  578.  
  579. EXTERN_API_C( void )
  580. CFStringTrimWhitespace            (CFMutableStringRef     theString);
  581.  
  582.  
  583. EXTERN_API_C( void )
  584. CFStringLowercase                (CFMutableStringRef     theString,
  585.                                  const void *            localeTBD);
  586.  
  587. EXTERN_API_C( void )
  588. CFStringUppercase                (CFMutableStringRef     theString,
  589.                                  const void *            localeTBD);
  590.  
  591. EXTERN_API_C( void )
  592. CFStringCapitalize                (CFMutableStringRef     theString,
  593.                                  const void *            localeTBD);
  594.  
  595.  
  596. /* This returns availability of the encoding on the system
  597. */
  598. EXTERN_API_C( Boolean )
  599. CFStringIsEncodingAvailable        (CFStringEncoding         encoding);
  600.  
  601. /* This function returns list of available encodings.  The returned list is terminated with kCFStringEncodingInvalidId and owned by the system.
  602. */
  603. EXTERN_API_C( const CFStringEncoding *)
  604. CFStringGetListOfAvailableEncodings (void);
  605.  
  606. /* Returns name of the encoding
  607. */
  608. EXTERN_API_C( CFStringRef )
  609. CFStringGetNameOfEncoding        (CFStringEncoding         encoding);
  610.  
  611. /* ID mapping functions from/to YellowBox NSStringEncoding.  Returns kCFStringEncodingInvalidId if no mapping exists.
  612. */
  613. EXTERN_API_C( UInt32 )
  614. CFStringConvertEncodingToNSStringEncoding (CFStringEncoding  encoding);
  615.  
  616. EXTERN_API_C( CFStringEncoding )
  617. CFStringConvertNSStringEncodingToEncoding (UInt32         encoding);
  618.  
  619. /* ID mapping functions from/to Microsoft Windows codepage (covers both OEM & ANSI).  Returns kCFStringEncodingInvalidId if no mapping exists.
  620. */
  621. EXTERN_API_C( UInt32 )
  622. CFStringConvertEncodingToWindowsCodepage (CFStringEncoding  encoding);
  623.  
  624. EXTERN_API_C( CFStringEncoding )
  625. CFStringConvertWindowsCodepageToEncoding (UInt32         codepage);
  626.  
  627. /* ID mapping functions from/to IANA registery charset names.  Returns kCFStringEncodingInvalidId if no mapping exists.
  628. */
  629. EXTERN_API_C( CFStringEncoding )
  630. CFStringConvertIANACharSetNameToEncoding (CFStringRef     theString);
  631.  
  632. EXTERN_API_C( CFStringRef )
  633. CFStringConvertEncodingToIANACharSetName (CFStringEncoding  encoding);
  634.  
  635.  
  636. /* The next two functions allow "fast" access to the contents of a string, 
  637.    assuming you are doing sequential or localized accesses. To use, call
  638.    CFStringInitInlineBuffer() with a CFStringInlineBuffer (on the stack, say),
  639.    and a range in the string to look at. Then call CFStringGetCharacterFromInlineBuffer()
  640.    as many times as you want, with a index into that range (relative to the start
  641.    of that range). These are INLINE functions and will end up calling CFString only 
  642.    once in a while, to fill a buffer.  
  643. */
  644. #define __kCFStringInlineBufferLength 64
  645. typedef struct {
  646.     UniChar buffer[__kCFStringInlineBufferLength];
  647.     CFStringRef theString;
  648.     const UniChar *directBuffer;
  649.     CFRange rangeToBuffer;        /* Range in string to buffer */
  650.     CFIndex bufferedRangeStart;        /* Start of range currently buffered (relative to rangeToBuffer.location) */
  651.     CFIndex bufferedRangeEnd;        /* bufferedRangeStart + number of chars actually buffered */
  652. } CFStringInlineBuffer;
  653.  
  654. #if defined(CF_INLINE)
  655. CF_INLINE void CFStringInitInlineBuffer(CFStringRef str, CFStringInlineBuffer *buf, CFRange range) {
  656.     buf->theString = str;
  657.     buf->rangeToBuffer = range;
  658.     buf->directBuffer = CFStringGetCharactersPtr(str);
  659.     buf->bufferedRangeStart = buf->bufferedRangeEnd = 0;
  660. }
  661.  
  662.  
  663. CF_INLINE UniChar CFStringGetCharacterFromInlineBuffer(CFStringInlineBuffer *buf, CFIndex idx) {
  664.     if (buf->directBuffer) return buf->directBuffer[idx + buf->rangeToBuffer.location];
  665.     if (idx >= buf->bufferedRangeEnd || idx < buf->bufferedRangeStart) {
  666.     if (idx < 0 || idx > buf->rangeToBuffer.length) return 0;
  667.     if ((buf->bufferedRangeStart = idx - 4) < 0) buf->bufferedRangeStart = 0;
  668.     buf->bufferedRangeEnd = buf->bufferedRangeStart + __kCFStringInlineBufferLength;
  669.     if (buf->bufferedRangeEnd > buf->rangeToBuffer.length) buf->bufferedRangeEnd = buf->rangeToBuffer.length;
  670.     CFStringGetCharacters(buf->theString, CFRangeMake(buf->rangeToBuffer.location + buf->bufferedRangeStart, buf->bufferedRangeEnd - buf->bufferedRangeStart), buf->buffer);
  671.     }
  672.     return buf->buffer[idx - buf->bufferedRangeStart];
  673. }
  674.  
  675. #else
  676. /* If INLINE functions are not available, we do somewhat less powerful macros that work similarly (except be aware that the buf argument ise evaluated multiple times).
  677. */
  678. #define CFStringInitInlineBuffer(str, buf, range) \
  679.     {(buf)->theString = str; (buf)->rangeToBuffer = range; (buf)->directBuffer = CFStringGetCharactersPtr(str);}
  680.  
  681. #define CFStringGetCharacterFromInlineBuffer(buf, idx) \
  682.     ((buf)->directBuffer ? (buf)->directBuffer[(idx) + (buf)->rangeToBuffer.location] : CFStringGetCharacterAtIndex((buf)->theString, (idx) + (buf)->rangeToBuffer.location))
  683.  
  684. #endif /* CF_INLINE */
  685.  
  686. /* Rest of the stuff in this file is private and should not be used directly
  687. */
  688. /* For debugging only
  689.    Use CFShow() to printf the description of any CFType;
  690.    Use CFShowStr() to printf detailed info about a CFString
  691. */
  692. EXTERN_API_C( void )
  693. CFShow                            (CFTypeRef                 obj);
  694.  
  695. EXTERN_API_C( void )
  696. CFShowStr                        (CFStringRef             str);
  697.  
  698. /* This function is private and should not be used directly
  699. */
  700. EXTERN_API_C( CFStringRef )
  701. __CFStringMakeConstantString    (const char *            cStr);
  702.  
  703. /* Private; do not use */
  704.  
  705. #if PRAGMA_STRUCT_ALIGN
  706.     #pragma options align=reset
  707. #elif PRAGMA_STRUCT_PACKPUSH
  708.     #pragma pack(pop)
  709. #elif PRAGMA_STRUCT_PACK
  710.     #pragma pack()
  711. #endif
  712.  
  713. #ifdef PRAGMA_IMPORT_OFF
  714. #pragma import off
  715. #elif PRAGMA_IMPORT
  716. #pragma import reset
  717. #endif
  718.  
  719. #ifdef __cplusplus
  720. }
  721. #endif
  722.  
  723. #endif /* __COREFOUNDATION_CFSTRING__ */
  724.  
  725.